Summary

• deterministically route explicit PiVoice remember, recall, and think-hard intents with honest failure postconditions
• preserve server-pushed speech across concurrent chat sentence-ID changes using explicit TTS arbitration
• persist the last observed firmware mutex across dotty-behaviour restarts
• replace the broken firmware onboarding path with the pinned Dotty fork, real Kconfig symbols, and the actual first-boot flow
• align firmware lineage, compatibility, release, and architecture documentation with fw-v1.3.3 and submodule 969c2b2
• guard onboarding documentation against regression and prevent raw local UAT media/logs from being accidentally committed
• keep the calendar route-shape test offline instead of silently contacting wttr.in

Root causes

Post-release live probes showed the 4B model still ignored tool-routing prompts, behaviour state was lost on container restart, and a deterministic harness reproduced a server-push sentence-ID race.

Issue #172 also exposed three independent documentation defects:

1. the source-build guide cloned the official m5stack/StackChan upstream instead of Dotty's pinned BrettKinny/StackChan@dotty firmware;
2. it recommended CONFIG_WIFI_SSID and CONFIG_WIFI_PASSWORD, which do not exist in the pinned Kconfig;
3. it treated “Welcome! Let's get started.” as a failed self-hosted setup, although the pinned firmware always shows that NVS-controlled StackChan wizard after a fresh flash.

The corrected path is: build the recursively cloned superproject's pinned firmware, set/verify CONFIG_OTA_URL, tap Skip, leave SETUP for Xiaozhi, then provision Wi-Fi through the temporary Xiaozhi-* hotspot. The browser portal—not the on-device Settings app—contains the optional Advanced ota_url field.

Impact

Third-party self-hosted installs now have a source-verified procedure that points at the firmware this repository actually releases. Repeat builds are warned that sdkconfig.defaults does not override an existing generated sdkconfig. Compatibility docs identify the coordinated release and no longer reference nonexistent backup tooling or stale pre-StateManager pins.

No production behavior code changed in the onboarding follow-up; the only behavior-test change removes an accidental live weather dependency.

Validation

• Ruff passed
• bridge/Pi Python: 181 passed plus 11 subtests
• dotty-behaviour: 235 passed
• onboarding regression suite: 7 passed
• dotty-pi-ext TypeScript suite passed
• git diff --check passed

The FastAPI suite was run outside Codex's restricted network/thread sandbox after an isolated route test proved the sandbox caused the lifespan startup stall; it completed in 7.85 seconds.

Still bench-pending

• clean-device flash and Xiaozhi hotspot provisioning using the corrected guide
• full live device-route acceptance for say bypass races chat turns under continuous ASR — sentence_id arbitration #104/UAT UT1/UT2/UT6: pi voice tools never invoked — qwen3.5:4b answers directly under the production prompt #165
• physical motion/dance, LEDs, audio arbitration, reconnect, safety, and kid-mode red-team checks

This PR was prepared with AI-assisted implementation, diagnosis, and review.